home *** CD-ROM | disk | FTP | other *** search
/ Joint Education Initiative / Joint Education Initiative.iso / dos / imdisp / imgprog.doc < prev    next >
Text File  |  1989-05-14  |  38KB  |  888 lines
  1.  
  2.  
  3.         PROGRAMMERS MANUAL FOR IMAGE DISPLAY AND I/O ROUTINES
  4.  
  5.  
  6.     IMDISP is written in a modular way so that it is easy to change
  7. it to work with different display devices or on other computers.
  8. The code can also easily be adapted for use in other application
  9. programs.  There are device dependent image display modules,
  10. general image display subroutines, image I/O routines, and image label
  11. and command line parsing routines.  The general purpose display routines
  12. can draw lines, write text with different fonts, manipulate a cursor,
  13. interactively adjust the palette, display histograms, etc.
  14. The IMDISP system is written in the "C" computer langauge.  
  15.  
  16.             Model of Device Independent Image Display
  17.  
  18.     The image display is modeled as having coordinates ranging from 1 to
  19. "dispnl" from top to bottom and from 1 to "dispns" from left to right
  20. (i.e. a line-sample space).  There is one image plane that can take
  21. on "numDN" values.  There is assumed to be a lookup table to convert
  22. those DN values into voltages for the red, green, and blue guns in the
  23. monitor.  There are "numshades" shades of each primary color for a total
  24. of numshades**3 different colors.  The palette is a table of numDN
  25. entries, with each entry containing the three primary color intensities
  26. on a scale from 0 to 255.
  27.  
  28.     There are five global variables that define the display
  29. characteristics and are set in the DISPDRIV module:  dispnl, dispns,
  30. numDN, numshades, OneScreen.  There are two related contants:
  31. MAXDISPNL and MAXDISPNS.
  32.  
  33. The cursor, text, and font global variables are in the DISPUTIL module.
  34. The image control block constants and variables are in the IMAGEIO module.
  35.  
  36.                 Compiling and Linking Routines
  37.  
  38.     This document describes the "C" language version of the IMDISP
  39. system.  The routines are written in Microsoft C version 5.1 on an 
  40. IBM AT compatible computer.  The large memory module is used.  There 
  41. is one module (dispsub.asm) written in 8086 assembly language for reasons
  42. of execution speed.
  43.  
  44. The following commands are are used to compile and link the subroutines 
  45. and programs.  They are contained in the COMPLINK.BAT file.
  46.  
  47. cl /AL /c dispio.c disputil.c fileio.c fileutil.c imageio.c imagutil.c  
  48. imdisp.c labutil.c memutil.c 
  49.  
  50. masm dispsub.asm;
  51.  
  52. link/NOE imdisp+dispsub+dispio+disputil+fileio+filesel+imagutil+
  53. imageio+labutil+memutil/stack:8000/exepack;
  54.  
  55.  
  56.              LIST OF PROGRAMS
  57.  
  58. IMDISP.C     - Main program, help, command drivers.
  59. DISPIO.C     - Display on/off, read/write lines, pixels, palette.
  60. DISPUTIL.C   - Font, cursor, text and palette routines.
  61. DISPSUB.ASM  - Assembly language routines for EGA/PGA display.
  62. FILEIO.C     - MSDOS and CDROM file input/output routines.
  63. FILEUTIL.C   - File menu and wild card routines.
  64. IMAGEIO.C    - Image open/close/read routines.
  65. IMAGUTIL.C   - Palette, histogram, profile and stretch routines.
  66. LABUTIL.C    - Label parsing routines.
  67. MEMUTIL.C    - Special memory allocation routines (malloc/free).
  68.  
  69. -----------------------------------------------------------------
  70.  
  71. Routines for image display
  72. --------------------------
  73.  
  74. Module: DISPIO
  75.  
  76.  DisplayOn
  77.  DisplayOff
  78.  WritePalette (palette)
  79.  WritePixel (line, sample, DNvalue)
  80.  ReadPixel (line, sample, DNvalue)
  81.  DisplayLine (buffer, line, samp, ns)
  82.  ClearDisplay (DNvalue)
  83.  PutRefresh (buffer, line, ss, ns)
  84.  GetRefresh (buffer, line, ss, ns)
  85.  
  86. Module: DISPSUB
  87.  
  88.  _putmem
  89.  _getmem 
  90.  WritePixelEGA (line, samp, DN)
  91.  DisplayLineEGA (buffer, line, samp, ns)
  92.  int ClearDisplayEGA (DN,dispnl)
  93.  _PGAsend        
  94.  _EGAinit        (initializes special 480 line EGA mode).
  95.  
  96. Module: DISPUTIL
  97.  
  98. InitDisplay
  99. ReadPalette (palette)
  100. DrawLine (line1, sample1, line2, sample2, DNvalue)
  101. DrawBox (line, samp, linesize, sampsize, DNvalue)
  102.  
  103. RemoveCursor
  104. PlaceCursor (line, sample, DNvalue)
  105. MoveCursor (line, sample)
  106.  
  107. Font (FontType)
  108. DrawText (text, line, sample, height, angle, DNvalue)
  109. LengthText (text, height, TextLength)
  110. TypeText (text)
  111. TypeTextLine (text)
  112. AcceptText (string)
  113. WriteText (text)
  114.  
  115. Module: IMAGUTIL
  116.  
  117. DiddlePalette (numcolors)
  118. DisplayHistogram (histbuffer, numbins, minDN, maxDN)
  119. Stretch (DNlow, DNhigh : Integer);
  120. Profile
  121.  
  122. Routines for image and file Input/Output
  123. ----------------------------------------
  124.  
  125. Module: FILEUTIL
  126.  
  127. FileSel (selFilename)
  128. Wildexp (argc, argv)
  129.  
  130. Module: IMAGEIO
  131.  
  132. OpenImage (filename, unit, IOmode, nl, ns, bitsperpix, status)
  133. ReadLine (unit, buffer, line, ss, ns, status)
  134. WriteLine (unit, buffer, line, ss, ns, status)
  135. CloseImage (unit, status)
  136. CheckStatus (status)
  137. ConvertLine (inbuffer, outbuffer, inbits, outbits, ns, status)
  138.  
  139.  
  140. Module: LABUTIL
  141.  
  142. GetLabelInteger (LabelBuf, Len, Keyword, default, value, flag)
  143. GetLabelReal (LabelBuf, Len, Keyword, default, value, flag)
  144. GetLabelString (LabelBuf, Len, Keyword, default, value, flag)
  145. InterpretLabel (LabelBuf, Len, labelsize, nline, nsamp, bitsperpix,
  146.                                reclen, lineheadbytes, DetachedFilename)
  147. MakeLabel (LabelBuf, labelsize, nline, nsamp, bitsperpix, reclen)
  148. GetCommand (CommandString, CommandList)
  149. GetKeywordInteger (CommandString, Keyword, default, value, flag)
  150. GetKeywordReal (CommandString, Keyword, default, value, flag)
  151. GetKeywordString (CommandString, Keyword, default, value, flag)
  152.  
  153. Module: FILEIO
  154.  
  155. OpenFile (filename, unit, IOmode, blocksize, status)
  156. ReadBlocks (unit, buffer, StartBlock, NumBlocks, BlocksRead, status)
  157. WriteBlocks (unit, buffer, StartBlock, NumBlocks, status)
  158. CloseFile (unit, status)
  159. InitializeCD (status)
  160. ReadBlocksCD (buffer, StartBlock, NumBlocks, status)
  161.  
  162.  
  163.              SUMMARY AND USE OF SUBROUTINES
  164.  
  165. /***    Module:    DISPIO
  166.  
  167.       DISPIO contains the device dependent display routines for
  168.       the Color Graphics Adapter (CGA), the Enhanced Graphics Adapter (EGA),
  169.       the Professional Graphics Adapter (PGA), and the Video Graphics Array
  170.       (VGA).  The global variables that define the device are allocated and 
  171.       initialized here.
  172. ***/
  173.  
  174. DisplayOn()
  175. /***  DisplayOn figures out which display device is on the system and
  176.       then initializes for that device.  The device is turned on.
  177.       The global variables that define the display characteristics
  178.       and the default color palette are initialized.  The refresh
  179.       buffer is zeroed.
  180. ***/
  181.  
  182. DisplayOff()
  183. /***  DisplayOff turns off the display device returning the screen
  184.       to text mode.
  185. ***/
  186.  
  187. WritePalette (coltab)
  188. /***  WritePalette updates the display device palette with the
  189.       palette passed in coltab.  coltab must be of type Color.
  190. ***/
  191.  
  192. WritePixel (line, sample, DN)
  193. /***  WritePixel writes a pixel on the display screen.
  194.       Parameter   type       description
  195.         line     integer     The line coordinate of the pixel
  196.         sample   integer     The sample coordinate of the pixel
  197.         DN       integer     The DN value of the pixel
  198. ***/
  199.  
  200. ReadPixel (line, sample, p_DN)
  201. /***  ReadPixel read a pixel value from the display screen.
  202.       Parameter   type       description
  203.         line     integer     The line coordinate of the pixel
  204.         sample   integer     The sample coordinate of the pixel
  205.         p_DN     int ptr     The DN value of the pixel is returned
  206. ***/
  207.  
  208. DisplayLine (buffer, line, sample, ns)
  209. /***  DisplayLine writes a line of pixels on the display screen.
  210.       Parameter   type       description
  211.         buffer   char ptr    The array of pixel values
  212.         line     integer     The line coordinate of the first pixel
  213.         sample   integer     The sample coordinate of the first pixel
  214.         ns       integer     The number of pixels to display
  215. ***/
  216.  
  217. ClearDisplay (DN)
  218. /***  ClearDisplay sets the whole display to a particular value.
  219.       Parameter   type       description
  220.         DN       integer     The DN value to set (usually 0)
  221. ***/
  222.  
  223. PutRefresh (buffer, line, ss, ns)
  224. /***  PutRefresh stores a line of pixels in the refresh buffer.
  225.       Parameter   type       description
  226.         buffer   char ptr    The array of pixel values
  227.         line     integer     The line coordinate of the first pixel
  228.         sample   integer     The sample coordinate of the first pixel
  229.         ns       integer     The number of pixels to store
  230. ***/
  231.  
  232. GetRefresh (buffer, line, ss, ns)
  233. /***  GetRefresh reads a line of pixels from the refresh buffer.
  234.       Parameter   type       description
  235.         buffer   char ptr    The receiving array of pixel values
  236.         line     integer     The line coordinate of the first pixel
  237.         sample   integer     The sample coordinate of the first pixel
  238.         ns       integer     The number of pixels to read
  239. ***/
  240.  
  241. --------------------------------------------------------------------------
  242.  
  243. /***  Module: DISPUTIL
  244.       Device Independant General Purpose Graphics Routines
  245.  
  246.     Includes line drawing, text display, and cursor routines.
  247.  
  248. ***/
  249.  
  250. InitDisplay()
  251. /*** InitDisplay turns the display device on, loads the default palette,
  252.     initializes the global variables, and loads the font arrays.
  253. ***/
  254.  
  255. ReadPalette (coltab)
  256. /***  ReadPalette returns the current color palette in coltab.
  257.       coltab is of type Color.
  258. ***/
  259.  
  260. DrawLine (x1, y1, x2, y2, color)
  261. /***  DrawLine draws a line of pixels from the first point to the
  262.     second point with the desired DN value.  Clipping is not performed.
  263.  
  264.        Parameter  Type   Description
  265.          x1       int    the line coordinate of the first point
  266.          y1       int    the sample coordinate of the first point
  267.          x2       int    the line coordinate of the second point
  268.          y2       int    the sample coordinate of the second point
  269.          color    int    the DN value of the drawn pixels
  270. ***/
  271.  
  272. DrawBox (line, samp, lsize, ssize, color)
  273. /*** DrawBox draws a solid rectangle on the screen.
  274.    Used for erasing parts of the screen.
  275.  
  276.     Parameter   Type     Description
  277.      line       int      starting line coordinate of rectangle
  278.      samp       int      starting sample coordinate of rectangle
  279.      lsize      int      number of lines in rectangle
  280.      ssize      int      number of samples in rectangle
  281.      color      int      the DN value to draw the box
  282. ***/
  283.  
  284. Font (FontType)
  285. /***  Font reads in the font file for type FontType and fills the
  286.     font arrays appropriately.  If FontType = 0 the internal font file
  287.     is used instead.  FontType = 5 reads in font file 005.FNT, etc.
  288.     The global variable thefont is set to the font number.
  289.  
  290.     The format of a font file is a sequence of bytes.  The first byte
  291.     is the number of characters defined in the font.  For each
  292.     character there is the following:  the ascii code, the number of
  293.     line strokes, the character width, and then the list of line strokes.
  294.     Each line stroke consists of three bytes: the pen motion, and the
  295.     x and y coordinate.  The width, x, and y values are converted
  296.     back into character coordinates by subtracting 50 and dividing
  297.     by 100.  The pen is 2 for pen down, and 3 for pen up.
  298. ***/
  299.  
  300. DrawText (text, line, sample, height, angle, DNvalue)
  301. /***  DrawText draws a text string on the display using the
  302.     current font.
  303.  
  304.     Parameter  Type     Description
  305.      text     char ptr  text string to display
  306.      line     int       line coordinate of lower left of first char
  307.      sample   int       sample coordinate of lower left of first char
  308.      height   int       height of characters in pixels
  309.      angle    int       angle in degrees ccw from positive sample direction
  310.      DNvalue  int       the DN value to draw the pixels in with
  311. ***/
  312.  
  313. LengthText (text, height, p_TextLength)
  314. /*** LengthText finds the length in pixels of a given text string.
  315.  
  316.     Parameter       Type     Description
  317.      text          char ptr   text string to display
  318.      height         int       height of characters in pixels
  319.      p_TextLength  int ptr    where to return length of string
  320. ***/
  321.  
  322. TypeText (TypeString)
  323. /***  TypeText displays a line of text on the screen at the current
  324.     text location with a height of 15 pixels.  The area is first erased.
  325.     The text position is advanced to the next position after the last
  326.     character.
  327.      Parameter       Type     Description
  328.      TypeString    char ptr   text string to display
  329. ***/
  330.  
  331. TypeTextLine (TypeString)
  332. /***  TypeTextLine displays a line of text on the screen using TypeText.
  333.     The text position is advanced to the beginning of the next line.
  334.      Parameter       Type     Description
  335.      TypeString    char ptr   text string to display
  336. ***/
  337.  
  338. AcceptText (AcceptString)
  339. /***  AcceptString gets a string from the keyboard.  The characters
  340.     are echoed on the display screen using DrawText.  The string is
  341.     terminated with a return (ascii 13).  Backspace deleting is supported.
  342.     The text position is left at the beginning of the next line.
  343.      Parameter       Type      Description
  344.      AcceptString    char ptr  returned text string from user
  345. ***/
  346.  
  347. WriteText (text)
  348. /***  WriteText writes out a line of text to the user.  If there
  349.     is only one screen then the text is written on the image display.
  350.     Otherwise it is written to the terminal.
  351.      Parameter     Type     Description
  352.      text        char ptr   text string to display
  353. ***/
  354.  
  355. RemoveCursor()
  356. /***  RemoveCursor removes the cursor, if it is on, from the display
  357.     screen, replacing the original pixel values.
  358. ***/
  359.  
  360. PlaceCursor (line, sample, cursDN)
  361. /***  PlaceCursor puts the cursor, if it is not already on, on the
  362.     screen, while storing the original pixel values.
  363.      Parameter     Type     Description
  364.       line         int      the line coordinate to put the cursor at
  365.       sample       int      the sample coordinate to put the cursor at
  366.       cursDN       int      the DN value of the cursor
  367. ***/
  368.  
  369. MoveCursor (p_line, p_sample)
  370. /***  MoveCursor performs the cursor mode operation.
  371.     The user moves the cursor around using the numeric keypad.
  372.     The cursor moves in discrete steps whose size can be changed.
  373.     The final cursor position is returned.
  374.  
  375.      Parameter     Type      Description
  376.       p_line     int ptr     the cursor line coordinate
  377.       p_sample   int ptr     the cursor sample coordinate
  378. ***/
  379.  
  380. --------------------------------------------------------------------------
  381.  
  382. /***  Module: IMAGUTIL
  383.       Special Purpose Device Independant Display Routines
  384.  
  385.     Contains high level display routines such as interactive palette
  386.     adjustment, histogram display, and image profile drawing.
  387.  
  388. ***/
  389.  
  390. DiddlePalette (numdiddle)
  391. /***  DiddlePalette performs interactive adjustment of the color
  392.     palette.  A wedge of numdiddle DN values, from 0 to the maximum,
  393.     is displayed at the bottom of the screen, and the palette is
  394.     changed to have only numdiddle distinct shades.  Then a loop
  395.     for user input is entered.  The active color is the one in the
  396.     wedge with the small black box inside it.
  397.  
  398.     The following is a list of commands:
  399.        Character      Action
  400.          4 (6)      move to next lower (higher) color in wedge
  401.          r (R)      decrease (increase) amount of red one notch
  402.          g (G)      decrease (increase) amount of green one notch
  403.          b (B)      decrease (increase) amount of blue one notch
  404.          2 (8)      decrease (increase) amount of all colors one notch
  405.          .          exit from palette diddle mode
  406.  
  407.     The wedge is erased after the user exits.
  408.  
  409.     Parameter   Type   Description
  410.      numdiddle   int   number of colors in the wedge and resulting palette
  411. ***/
  412.  
  413. DisplayHistogram (histbuf, numbins, minDN, maxDN)
  414. /***  DisplayHistogram diplays the passed histogram on the screen.
  415.     The third highest bin in the histogram is used to scale the
  416.     plot.  The axes of the plot are labeled and annotated.  The
  417.     number in each bin is indicated by the length of the line
  418.     drawn vertically from the axis.
  419.  
  420.      Parameter  Type            Description
  421.       histbuf   long int array  the array of count values for each bin
  422.       numbins   int             the number of bins in the histogram
  423.       minDN     int             the minimum DN value in the histogram
  424.       maxDN     int             the maximum DN value in the histogram
  425. ***/
  426.  
  427. Stretch (DNlow, DNhigh)
  428. /***  Stretch applies a linear gray scale ramp to the palette
  429.     starting with 0 at Dnlow and proceeding to 255 at DNhigh.
  430.  
  431.      Parameter  Type   Description
  432.       DNlow     int    the starting DN value of the linear ramp
  433.       DNhigh    int    the ending DN value of the linear ramp
  434. ***/
  435.  
  436. Profile()
  437. /***  Profile plots a profile of the pixel values between two points
  438.     on the screen.  Cursor mode is used to select the two endpoints.
  439.     A line is drawn between the endpoints and a plot of DN value
  440.     versus distance along the line is made.
  441. ***/
  442.  
  443. --------------------------------------------------------------------------
  444.  
  445. /***  Module:  IMAGEIO
  446.      Image I/O routines for labeled images
  447.  
  448.      Includes routines for opening images, reading and writing
  449.      image lines, and converting pixel formats.
  450.  
  451. ***/
  452.  
  453. OpenImage (filename, unit, IOmode, p_nline, p_nsamp, p_bitsperpix, status)
  454. /***  OpenImage opens an image file either for reading or writing.
  455.       The size of the image and pixel format are returned if the file
  456.       is opened for reading.  If the file is opened for writing
  457.       then the passed number of lines and samples and pixel format are
  458.       used for the new image.  The unit number is used to refer to the
  459.       file in subsequent operations.  If the file is opened for input
  460.       then the label processing routines will parse Vicar2 and PDS
  461.       labels and will prompt for user info if the image is unlabeled.
  462.       PDS detached labels are handled transparently in this routine.
  463.       If the file is for writing then a PDS label will be output.
  464.       An error is returned if there is insufficient room to dynamically
  465.       allocate the image buffer, or if there is a file error.
  466.       For images with pixel sizes less than a byte, each line is assumed
  467.       to start with a new byte.
  468.  
  469.    Parameter    Type    In/out  Description
  470.  
  471.     filename  char ptr   in     Name of image file to open
  472.     unit        int      in     Unit number of image (0,1,2...)
  473.     IOmode    char ptr   in     Access mode of file
  474.                                   ("r..." for reading, "w..." for writing)
  475.     p_nline   int ptr  in/out   The number of lines in the image
  476.     p_nsamp   int ptr  in/out   The number of samples in the image
  477.  p_bitsperpix int ptr  in/out   The number of bits in a pixel (pixel format)
  478.                                   (16 for integer, 8 for byte,
  479.                                     4 for nibble,  1 for binary)
  480.     status    char ptr  out     Return string with error message
  481.                                   (0 length string if no error)
  482. ***/
  483.  
  484. ReadLine (unit, buffer, line, ss, ns, status)
  485. /***  ReadLine reads a line of pixels from the image into the user's
  486.     buffer.  The reading is completely random access, the lines may
  487.     be read in any order; it is more efficient, however, to read lines
  488.     sequentially.  Partial image lines may be read.  The output data
  489.     is in the same format as the file (the convert routine may be
  490.     used to convert pixel formats).
  491.  
  492.    Parameter Type   In/out  Description
  493.  
  494.     unit     int      in     Unit number of image (same as in open)
  495.     buffer  char ptr  out    Buffer to receive pixels
  496.     line     int      in     The number of the image line to read (1 is first)
  497.     ss       int      in     The starting sample in the line
  498.     ns       int      in     The number of samples to read into buffer
  499.     status  char ptr  out    Return string with error message
  500.                                   (0 length string if no error)
  501. ***/
  502.  
  503. WriteLine (unit, buffer, line, ss, ns, status)
  504. /***  WriteLine writes a line of pixels from the user buffer to the image.
  505.     Although the writing is buffered, completely random access will not
  506.     work; the image lines should be written sequentially.
  507.     Partial image lines may be written.  The input data must be in the
  508.     same format as the file (no conversion is performed).
  509.  
  510.    Parameter Type   In/out  Description
  511.  
  512.     unit     int      in     Unit number of image (same as in open)
  513.     buffer  char ptr  in     Buffer of image pixels
  514.     line     int      in     The number of the image line to write
  515.     ss       int      in     The starting sample in the line
  516.     ns       int      in     The number of samples to write from buffer
  517.     status  char ptr  out    Return string with error message
  518.                                   (0 length string if no error)
  519. ***/
  520.  
  521. CloseImage (unit, status)
  522. /***  CloseImage closes the image file.  If the image is opened for
  523.     writing then the image buffer is first flushed.
  524.  
  525.    Parameter Type   In/out  Description
  526.  
  527.     unit     int      in     Unit number of image (same as in open)
  528.     status  char ptr  out    Return string with error message
  529.                                   (0 length string if no error)
  530. ***/
  531.  
  532. CheckStatus (status)
  533. /***  CheckStatus checks the status string passed in.  If there
  534.     is no error the routine returns, otherwise the error message
  535.     is printed to the terminal and the program is aborted.
  536.  
  537. ***/
  538.  
  539. ConvertLine (inbuffer, outbuffer, inbits, outbits, ns, status)
  540. /***  ConvertLine converts a line of pixels into a different format.
  541.  
  542.    Parameter     Type   In/out  Description
  543.  
  544.     inbuffer   char ptr  in    The input buffer of pixels
  545.     outbuffer  char ptr  out   The output buffer of pixels
  546.     inbits      int      in    The pixel format of the input buffer
  547.     outbits     int      in    The pixel format of the output buffer
  548.     ns          int      in    The number of samples to convert
  549.     status     char ptr  out   Return string with error message
  550.  
  551.  
  552.    Conversions supported :        outbits
  553.                                 1  4  8  16
  554.                    inbits    1  .  -  .  .      . means supported
  555.                              4  -  .  .  .
  556.                              8  .  .  .  .
  557.                             16  .  .  .  .
  558. ***/
  559.  
  560. --------------------------------------------------------------------------
  561.  
  562. /***  Module: LABUTIL
  563.      Label Processing Routines
  564. ***/
  565.  
  566.  
  567. GetLabelInteger (LabelBuf, LabelBufLen, Keyword, defaul, p_value, p_flag)
  568. /***  GetLabelInteger returns the integer value following the keyword in the
  569.     label buffer.  If the keyword is not there then the default value
  570.     is returned.  The flag indicates whether the keyword is there.
  571.  
  572.    Parameter    Type    In/out   Description
  573.     LabelBuf  char ptr   in      The buffer containing the label
  574.     LabelBufLen  int     in      The length in bytes of the label buffer
  575.     Keyword   char ptr   in      The keyword string to match
  576.     defaul       int     in      The value to return if no keyword or value
  577.     p_value    int ptr   out     The returned value
  578.     p_flag     int ptr   out     The flag: -1 if no keyword match
  579.                                    0 if illegal value, 1 if keyword and value
  580. ***/
  581.  
  582.  
  583.  
  584. GetLabelReal (LabelBuf, LabelBufLen, Keyword, defaul, p_value, p_flag)
  585. /***  GetLabelReal returns the real value following the keyword in the
  586.     label buffer.  If the keyword is not there then the default value
  587.     is returned.  The flag indicates whether the keyword is there.
  588.  
  589.    Parameter    Type    In/out   Description
  590.     LabelBuf  char ptr   in      The buffer containing the label
  591.     LabelBufLen  int     in      The length in bytes of the label buffer
  592.     Keyword   char ptr   in      The keyword string to match
  593.     defaul      float    in      The value to return if no keyword or value
  594.     p_value   float ptr  out     The returned value
  595.     p_flag     int ptr   out     The flag: -1 if no keyword match
  596.                                    0 if illegal value, 1 if keyword and value
  597. ***/
  598.  
  599.  
  600.  
  601. GetLabelString (LabelBuf, LabelBufLen, Keyword, defaul, value, p_flag)
  602. /***  GetLabelString returns the string value following the keyword in the
  603.     label buffer.  If the keyword is not there then the default value
  604.     is returned.  The flag indicates whether the keyword is there.
  605.  
  606.    Parameter    Type    In/out   Description
  607.     LabelBuf  char ptr   in      The buffer containing the label
  608.     LabelBufLen  int     in      The length in bytes of the label buffer
  609.     Keyword   char ptr   in      The keyword string to match
  610.     defaul    char ptr   in      The value to return if no keyword or value
  611.     p_value   char ptr   out     The returned value
  612.     p_flag     int ptr   out     The flag: -1 if no keyword match
  613.                                    0 if illegal value, 1 if keyword and value
  614. ***/
  615.  
  616. InterpretLabel (buf, len, p_labelsize, p_nline, p_nsamp,
  617.                      p_bitsperpix, p_reclen, p_lineheadbytes,
  618.                        DetachedFileName)
  619. /***  InterpretLabel interprets the label in the buffer to extract
  620.     the image information.  First something is identified to determine
  621.     whether the image has a PDS label or a Vicar2 label or no label.
  622.     If the image is labeled then the appropriate keyword values are
  623.     extracted, otherwise the user is prompted for the into.
  624.  
  625.    Parameter    Type   In/out  Description
  626.     buf        char ptr  in    The label buffer
  627.     len          int     in    The length in bytes of the label buffer
  628.   p_labelsize   int ptr  out   The size of the label or header to skip
  629.   p_nline       int ptr  out   The number of lines in the image
  630.   p_nsamp       int ptr  out   The number of samples in the image
  631.   p_bitsperpix  int ptr  out   The pixel format (16,8,4,1)
  632.   p_reclen      int ptr  out   The record length in bytes
  633. p_lineheadbytes int ptr  out   The header bytes at beginning of each line
  634. DetachedFileName char ptr out  The name of the file of data
  635.                                    null string if no detached label
  636. ***/
  637.  
  638. MakeLabel (Buf, p_labelsize, nline, nsamp, bitsperpix, reclen)
  639. /***  MakeLabel creates a PDS label in the buffer, having the appropriate
  640.     image parameters.
  641.  
  642.    Parameter    Type   In/out  Description
  643.     Buf        char ptr  out   The label buffer
  644.   p_labelsize  int ptr   out   The size of the label
  645.     nline       int      out   The number of lines in the image
  646.     nsamp       int      out   The number of samples in the image
  647.     bitsperpix  int      out   The pixel format (16,8,4,1)
  648.     reclen      int      out   The record length in bytes
  649.  
  650. ***/
  651.  
  652. int GetCommand (CommandString, CommandList)
  653. /***  GetCommand is an integer function that returns the number of
  654.     the command that is in the beginning of the CommandString parameter.
  655.     The command is assigned a number according to the list of
  656.     commands in the CommandList string parameter.  The list of commands
  657.     should be in uppercase and have spaces between the commmand.
  658.  
  659. ***/
  660.  
  661. GetKeywordInteger (CommandString, Keyword, defaul, p_value, p_flag)
  662. /***  GetKeywordInteger scans the CommandString for the Keyword
  663.     and returns the value of the following integer.
  664.  
  665.    Parameter       Type      In/out   Description
  666.     CommandString  char ptr    in      The command string to scan thru
  667.     Keyword        char ptr    in      The keyword string to match
  668.     defaul          int        in      The default value to return if
  669.                                            no keyword or illegal value
  670.     p_value        int ptr     out     The returned value
  671.     p_flag         int ptr     out     The flag:  -1 for no keyword match
  672.                                            0 for keyword with no/bad value
  673.                                            1 for keyword and good value
  674. ***/
  675.  
  676. GetKeywordReal (CommandString, Keyword, defaul, p_value, p_flag)
  677. /***  GetKeywordReal scans the CommandString for the Keyword
  678.     and returns the value of the following real.
  679.  
  680.    Parameter       Type      In/out   Description
  681.     CommandString  char ptr    in      The command string to scan thru
  682.     Keyword        char ptr    in      The keyword string to match
  683.     defaul          float      in      The default value to return if
  684.                                            no keyword or illegal value
  685.     p_value        float ptr   out     The returned value
  686.     p_flag         int ptr     out     The flag:  -1 for no keyword match
  687.                                            0 for keyword with no/bad value
  688.                                            1 for keyword and good value
  689. ***/
  690.  
  691. GetKeywordString (CommandString, Keyword, defaul, value, p_flag)
  692. /***  GetKeywordString scans the CommandString for the Keyword
  693.     and returns the value of the following string.
  694.  
  695.    Parameter       Type      In/out   Description
  696.     CommandString  char ptr    in      The command string to scan thru
  697.     Keyword        char ptr    in      The keyword string to match
  698.     defaul         char ptr    in      The default value to return if
  699.                                            no keyword or illegal value
  700.     p_value        char ptr    out     The returned value
  701.     p_flag         int ptr     out     The flag:  -1 for no keyword match
  702.                                            0 for keyword with no/bad value
  703.                                            1 for keyword and good value
  704. ***/
  705.  
  706. --------------------------------------------------------------------------
  707.  
  708. /***  Module:  FILEIO
  709.      Contains block level I/O routines for MS-DOS files.
  710.  
  711. ***/
  712.  
  713. OpenFile (filename, unit, IOmode, p_blocksize, status)
  714. /***  OpenFile opens a file with the given file name.
  715.     The file may be open for reading or writing.
  716.     If the file name begins with "CD:" then it is assumed to be an
  717.     absolute CD-ROM file on a non-standard CD-ROM.  The file name is
  718.     of the form "CD:mm:ss:bb", where mm is the minute of the starting
  719.     sector, ss is the second, and bb is the block number within the second.
  720.     The logical blocksize to be used in the image I/O routines
  721.     is returned.
  722.  
  723.    Parameter    Type    In/out   Description
  724.     filename   char ptr  in      File name string
  725.     unit        int      in      Unit number (0,1,2...)
  726.     IOmode     char ptr  in      "r..." for reading, 'w...' for writing
  727.    p_blocksize  int ptr  out     The returned logical blocksize to use
  728.     status     char ptr  out     The error message string
  729.                                      (0 length for no error)
  730. ***/
  731.  
  732. ReadBlocks (unit, buffer, startblock, numblocks, p_blocksread, status)
  733. /***  ReadBlocks reads blocks from the file into the buffer.
  734.  
  735.    Parameter    Type    In/out   Description
  736.     unit        int      in      Unit number from open
  737.     buffer     char ptr  out     The output buffer of data
  738.     startblock long int  in      The starting logical block
  739.     numblocks   int      in      The number of blocks to read
  740.  p_blocksread  int ptr   out     The number of blocks actually read
  741.     status     char ptr  out     The error message string
  742.                                      (0 length for no error)
  743. ***/
  744.  
  745. WriteBlocks (unit, buffer, startblock, numblocks, status)
  746. /***  WriteBlocks writes blocks from the buffer to the file.
  747.  
  748.    Parameter    Type    In/out   Description
  749.     unit        int      in      Unit number from open
  750.     buffer     char ptr  in      The input buffer of data
  751.     startblock long int  in      The starting logical block
  752.     numblocks   int      in      The number of blocks to write
  753.     status     char ptr  out     The error message string
  754.                                      (0 length for no error)
  755. ***/
  756.  
  757. CloseFile (unit, status)
  758. /*** CloseFile closes the file.
  759.  
  760.    Parameter    Type    In/out   Description
  761.     unit        int      in      Unit number from open
  762.     status     char ptr  out     The error message string
  763.                                      (0 length for no error)
  764. ***/
  765.  
  766. --------------------------------------------------------------------------
  767.  
  768. InitializeCD (p_PB_size, status)
  769. /***  InitializeCD initializes the CD player and returns the
  770.     physical block size.
  771.  
  772.     Parameter   Type      Description
  773.     p_PB_size   int ptr   The size of the physical blocks for this driver.
  774.                           (in this case 2048 bytes)
  775.     status      char ptr  Error message string (0 length if no error)
  776.  
  777. ***/
  778.  
  779. ReadBlocksCD (buffer, StartPB, NumPB, status)
  780. /***  ReadBlocksCD reads blocks from the CD-ROM to the user's buffer.
  781.  
  782.    Parameter    Type      Description
  783.     buffer     char ptr   Buffer to receive data
  784.     StartPB    long int   The starting absolute physical block
  785.     NumPB      int        The number of physical blocks to read
  786.     status     char ptr   Error message string (0 length if no error)
  787.  
  788. ***/
  789. --------------------------------------------------------------------------
  790.  
  791.     Low Level Block I/O with MS-DOS for non-standard CD-ROM's
  792.  
  793. InitializeCD (p_PB_size, status)
  794. /***  InitializeCD initializes the CD player and returns the
  795.     physical block size.
  796.  
  797.     Parameter   Type      Description
  798.     p_PB_size   int ptr   The size of the physical blocks for this driver.
  799.                           (in this case 2048 bytes)
  800.     status      char ptr  Error message string (0 length if no error)
  801.  
  802. ***/
  803.  
  804. ReadBlocksCD (buffer, StartPB, NumPB, status)
  805. /***  ReadBlocksCD reads blocks from the CD-ROM to the user's buffer.
  806.  
  807.    Parameter    Type      Description
  808.     buffer     char ptr   Buffer to receive data
  809.     StartPB    long int   The starting absolute physical block
  810.     NumPB      int        The number of physical blocks to read
  811.     status     char ptr   Error message string (0 length if no error)
  812.  
  813. ***/
  814. --------------------------------------------------------------------
  815.  
  816. /***  Module:  FILEUTIL
  817.      Contains file selection and wildcard expansion routines.
  818. ***/
  819.  
  820. int FileSel(selFilename)
  821. /*** filesel -- allow user to browse directories and select image 
  822.                 files for display.  Returns selected file name.
  823.    Parameter    Type       Description 
  824.     selFilename char ptr   filename selected for processing.
  825. ***/
  826.  
  827. wildexp(oargcp, oargvp)
  828. /*** wildexp -- expand wildcard file name.  Returns array of pointers
  829.                 to filenames meeting wildcard specifications.
  830.    Parameter    Type       Description 
  831.     oargcp    int ptr      pointer to number of values in oargvp
  832.     oargvp char ptr ptr ptr pointers to text strings containing
  833.                            file names meeting wild card specification.
  834. ***/
  835.  
  836.                      Memory Allocation Procedures
  837.  
  838.              Willard Gersbacher  - CompuServe User ID: (76117,2611)
  839.  
  840. The procedures included in this archive provide functionally equivalent
  841. memory allocation procedures for the main memory procedures used in C. 
  842. These procedures were written primarily because of a need to minimize
  843. memory usage for a large program under development.  The MSC 5.1
  844. library procedures were not satisfactory for this application because
  845. they did not release memory back to the system when it was 'free'ed. 
  846. Additionally, they tended to allocate too much memory under certain
  847. circumstances which lead to a reduction in space available for other
  848. programs and data which were currently active at the time.
  849.  
  850. These procedures should only be used with large data model programs
  851. (i.e., compact, large, and huge memory models).  No provision has been
  852. made for small or medium model programs.  
  853.  
  854. /* The following routines from the ALLOC.ARC distribution file 
  855.    have all been incorporated in MEMUTIL.C */
  856.  
  857.    free.c       -  Functional equivalent to free.  Included in this
  858.                    file is an additional procedure _ffree which calls
  859.                    free.
  860.  
  861.    malloc.c     -  Functional equivalent of malloc.  This file also 
  862.                    contains the memory structures which are used to
  863.                    keep track of the blocks of memory allocated.  In
  864.                    addition, the procedure _fmalloc is defined which
  865.                    just makes a call to malloc.
  866.  
  867.    memutil.c    -  This file contains a set of procedures which are
  868.                    used by the main memory allocation procedures to
  869.                    maintain the memory structure used to keep track of
  870.                    the user allocations and frees.
  871.  
  872.    reduceal.c   -  This procedure may be called to reduce the memory
  873.                    allocated to a program.  It attempts to release back
  874.                    to DOS the memory not currently being used.
  875.  
  876.    reducedd.c   -  This procedure may be called to reduce the default
  877.                    data segment to the minimum size required.  Normally
  878.                    this should be called before any calls to memory
  879.                    allocation procedures.  Included in this file are
  880.                    dummy procedures for _nmalloc and _nfree.  These
  881.                    latter procedures were included because some
  882.                    of the MSC library uses the near heap for memory
  883.                    allocation (even though you may be using large
  884.                    data model programs).  Since this procedure does
  885.                    away with any space which might be used for near
  886.                    heap allocation, this forces the procedures which
  887.                    call them to use the 'far' heap.
  888.